home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 2000 August: Tool Chest / Dev.CD Aug 00 TC Disk 1.toast / pc / sample code / files / standard file / standardgetfolder / moredesktopmgr.h < prev    next >
Encoding:
C/C++ Source or Header  |  2000-06-23  |  19.9 KB  |  543 lines
  1. /*
  2.     File:        MoreDesktopMgr.h
  3.     
  4.     Description:A collection of useful high-level Desktop Manager routines.
  5.                 If the Desktop Manager isn't available, use the Desktop file
  6.                 for 'read' operations.
  7.                 We do more because we can...
  8.  
  9.     Author:        JL & NG
  10.  
  11.     Copyright:     Copyright: © 1992-1999 by Apple Computer, Inc.
  12.                 all rights reserved.
  13.     
  14.     Disclaimer:    You may incorporate this sample code into your applications without
  15.                 restriction, though the sample code has been provided "AS IS" and the
  16.                 responsibility for its operation is 100% yours.  However, what you are
  17.                 not permitted to do is to redistribute the source as "DSC Sample Code"
  18.                 after having made changes. If you're going to re-distribute the source,
  19.                 we require that you make it clear in the source that the code was
  20.                 descended from Apple Sample Code, but that you've made changes.
  21.     
  22.     Change History (most recent first):
  23.                 6/25/99    Updated for Metrowerks Codewarror Pro 2.1(KG)
  24. */
  25. #ifndef __MOREDESKTOPMGR__
  26. #define __MOREDESKTOPMGR__
  27.  
  28. #include <Types.h>
  29. #include <Files.h>
  30.  
  31. #include "Optimization.h"
  32.  
  33. #ifdef __cplusplus
  34. extern "C" {
  35. #endif
  36.  
  37. /*****************************************************************************/
  38.  
  39. pascal    OSErr    DTOpen(ConstStr255Param volName,
  40.                        short vRefNum,
  41.                        short *dtRefNum,
  42.                        Boolean *newDTDatabase);
  43. /*    ¶ Open a volume's desktop database and return the desktop database refNum.
  44.     The DTOpen function opens a volume's desktop database. It returns
  45.     the reference number of the desktop database and indicates if the
  46.     desktop database was created as a result of this call (if it was created,
  47.     then it is empty).
  48.  
  49.     volName            input:    A pointer to the name of a mounted volume
  50.                             or nil.
  51.     vRefNum            input:    Volume specification.
  52.     dtRefNum        output:    The reference number of Desktop Manager's
  53.                             desktop database on the specified volume.
  54.     newDTDatabase    output:    true if the desktop database was created as a
  55.                             result of this call and thus empty.
  56.                             false if the desktop database was already created,
  57.                             or if it could not be determined if it was already
  58.                             created.
  59.     
  60.     Result Codes
  61.         noErr                0        No error
  62.         nsvErr                -35        Volume not found
  63.         ioErr                -36        I/O error
  64.         paramErr            -50        Volume doesn't support this function
  65.         extFSErr            -58        External file system error - no file
  66.                                     system claimed this call.
  67.         desktopDamagedErr    -1305    The desktop database has become corrupted - 
  68.                                     the Finder will fix this, but if your
  69.                                     application is not running with the
  70.                                     Finder, use PBDTReset or PBDTDelete
  71. */
  72.  
  73. /*****************************************************************************/
  74.  
  75. pascal    OSErr    DTXGetAPPL(ConstStr255Param volName,
  76.                            short vRefNum,
  77.                            OSType creator,
  78.                            Boolean searchCatalog,
  79.                            short *applVRefNum,
  80.                            long *applParID,
  81.                            Str255 applName);
  82. /*    ¶ Find an application on a volume that can open a file with a given creator.
  83.     The DTXGetAPPL function finds an application (file type 'APPL') with
  84.     the specified creator on the specified volume. It first tries to get
  85.     the application mapping from the desktop database. If that fails,
  86.     then it tries to find an application in the Desktop file. If that
  87.     fails and searchCatalog is true, then it tries to find an application
  88.     with the specified creator using the File Manager's CatSearch routine. 
  89.  
  90.     volName            input:    A pointer to the name of a mounted volume
  91.                             or nil.
  92.     vRefNum            input:    Volume specification.
  93.     creator            input:    The file's creator type.
  94.     searchCatalog    input:    If true, search the catalog for the application
  95.                             if it isn't found in the desktop database.
  96.     applVRefNum        output:    The volume reference number of the volume the
  97.                             application is on.
  98.     applParID        output:    The parent directory ID of the application.
  99.     applName        output:    The name of the application.
  100.     
  101.     Result Codes
  102.         noErr                0        No error
  103.         nsvErr                -35        Volume not found
  104.         ioErr                -36        I/O error
  105.         paramErr            -50        No default volume
  106.         rfNumErr            -51        Reference number invalid
  107.         extFSErr            -58        External file system error - no file
  108.                                     system claimed this call
  109.         desktopDamagedErr    -1305    The desktop database has become corrupted - 
  110.                                     the Finder will fix this, but if your
  111.                                     application is not running with the
  112.                                     Finder, use PBDTReset or PBDTDelete
  113.         afpItemNotFound        -5012    Information not found
  114.     
  115.     __________
  116.     
  117.     Also see:    FSpDTGetAPPL
  118. */
  119.  
  120. /*****************************************************************************/
  121.  
  122. pascal    OSErr    FSpDTXGetAPPL(ConstStr255Param volName,
  123.                               short vRefNum,
  124.                               OSType creator,
  125.                               Boolean searchCatalog,
  126.                               FSSpec *spec);
  127. /*    ¶ Find an application on a volume that can open a file with a given creator.
  128.     The FSpDTXGetAPPL function finds an application (file type 'APPL') with
  129.     the specified creator on the specified volume. It first tries to get
  130.     the application mapping from the desktop database. If that fails,
  131.     then it tries to find an application in the Desktop file. If that
  132.     fails and searchCatalog is true, then it tries to find an application
  133.     with the specified creator using the File Manager's CatSearch routine. 
  134.  
  135.     volName            input:    A pointer to the name of a mounted volume
  136.                             or nil.
  137.     vRefNum            input:    Volume specification.
  138.     creator            input:    The file's creator type.
  139.     searchCatalog    input:    If true, search the catalog for the application
  140.                             if it isn't found in the desktop database.
  141.     spec            output:    FSSpec record containing the application name and
  142.                             location.
  143.     
  144.     Result Codes
  145.         noErr                0        No error
  146.         nsvErr                -35        Volume not found
  147.         ioErr                -36        I/O error
  148.         paramErr            -50        No default volume
  149.         rfNumErr            -51        Reference number invalid
  150.         extFSErr            -58        External file system error - no file
  151.                                     system claimed this call
  152.         desktopDamagedErr    -1305    The desktop database has become corrupted - 
  153.                                     the Finder will fix this, but if your
  154.                                     application is not running with the
  155.                                     Finder, use PBDTReset or PBDTDelete
  156.         afpItemNotFound        -5012    Information not found
  157.     
  158.     __________
  159.     
  160.     Also see:    FSpDTGetAPPL
  161. */
  162.  
  163. /*****************************************************************************/
  164.  
  165. pascal    OSErr    DTGetAPPL(ConstStr255Param volName,
  166.                           short vRefNum,
  167.                           OSType creator,
  168.                           short *applVRefNum,
  169.                           long *applParID,
  170.                           Str255 applName);
  171. /*    ¶ Find an application on a volume that can open a file with a given creator.
  172.     The DTGetAPPL function finds an application (file type 'APPL') with
  173.     the specified creator on the specified volume. It first tries to get
  174.     the application mapping from the desktop database. If that fails,
  175.     then it tries to find an application in the Desktop file. If that
  176.     fails, then it tries to find an application with the specified creator
  177.     using the File Manager's CatSearch routine. 
  178.  
  179.     volName        input:    A pointer to the name of a mounted volume
  180.                         or nil.
  181.     vRefNum        input:    Volume specification.
  182.     creator        input:    The file's creator type.
  183.     applVRefNum    output:    The volume reference number of the volume the
  184.                         application is on.
  185.     applParID    output:    The parent directory ID of the application.
  186.     applName    output:    The name of the application.
  187.     
  188.     Result Codes
  189.         noErr                0        No error
  190.         nsvErr                -35        Volume not found
  191.         ioErr                -36        I/O error
  192.         paramErr            -50        No default volume
  193.         rfNumErr            -51        Reference number invalid
  194.         extFSErr            -58        External file system error - no file
  195.                                     system claimed this call
  196.         desktopDamagedErr    -1305    The desktop database has become corrupted - 
  197.                                     the Finder will fix this, but if your
  198.                                     application is not running with the
  199.                                     Finder, use PBDTReset or PBDTDelete
  200.         afpItemNotFound        -5012    Information not found
  201.     
  202.     __________
  203.     
  204.     Also see:    FSpDTGetAPPL
  205. */
  206.  
  207. /*****************************************************************************/
  208.  
  209. pascal    OSErr    FSpDTGetAPPL(ConstStr255Param volName,
  210.                              short vRefNum,
  211.                              OSType creator,
  212.                              FSSpec *spec);
  213. /*    ¶ Find an application on a volume that can open a file with a given creator.
  214.     The FSpDTGetAPPL function finds an application (file type 'APPL') with
  215.     the specified creator on the specified volume. It first tries to get
  216.     the application mapping from the desktop database. If that fails,
  217.     then it tries to find an application in the Desktop file. If that
  218.     fails, then it tries to find an application with the specified creator
  219.     using the File Manager's CatSearch routine. 
  220.  
  221.     volName        input:    A pointer to the name of a mounted volume
  222.                         or nil.
  223.     vRefNum        input:    Volume specification.
  224.     creator        input:    The file's creator type.
  225.     spec        output:    FSSpec record containing the application name and
  226.                         location.
  227.     
  228.     Result Codes
  229.         noErr                0        No error
  230.         nsvErr                -35        Volume not found
  231.         ioErr                -36        I/O error
  232.         paramErr            -50        No default volume
  233.         rfNumErr            -51        Reference number invalid
  234.         extFSErr            -58        External file system error - no file
  235.                                     system claimed this call
  236.         desktopDamagedErr    -1305    The desktop database has become corrupted - 
  237.                                     the Finder will fix this, but if your
  238.                                     application is not running with the
  239.                                     Finder, use PBDTReset or PBDTDelete
  240.         afpItemNotFound        -5012    Information not found
  241.     
  242.     __________
  243.     
  244.     Also see:    DTGetAPPL
  245. */
  246.  
  247. /*****************************************************************************/
  248.  
  249. pascal    OSErr    DTGetIcon(ConstStr255Param volName,
  250.                           short vRefNum,
  251.                           short iconType,
  252.                           OSType fileCreator,
  253.                           OSType fileType,
  254.                           Handle *iconHandle);
  255. /*    ¶ Get an icon from the desktop database or Desktop file.
  256.     The DTGetIcon function retrieves the specified icon and returns it in
  257.     a newly created handle. The icon is retrieves from the Desktop Manager
  258.     or if the Desktop Manager is not available, from the Finder's Desktop
  259.     file. Your program is responsible for disposing of the handle when it is
  260.     done using the icon.
  261.  
  262.     volName        input:    A pointer to the name of a mounted volume
  263.                         or nil.
  264.     vRefNum        input:    Volume specification.
  265.     iconType    input:    The icon type as defined in Files.h. Valid values are:
  266.                             kLargeIcon
  267.                             kLarge4BitIcon
  268.                             kLarge8BitIcon
  269.                             kSmallIcon
  270.                             kSmall4BitIcon
  271.                             kSmall8BitIcon
  272.     fileCreator    input:    The icon's creator type.
  273.     fileType    input:    The icon's file type.
  274.     iconHandle    output:    A Handle containing the newly created icon.
  275.     
  276.     Result Codes
  277.         noErr                0        No error
  278.         nsvErr                -35        Volume not found
  279.         ioErr                -36        I/O error
  280.         paramErr            -50        Volume doesn't support this function
  281.         rfNumErr            -51        Reference number invalid
  282.         extFSErr            -58        External file system error - no file
  283.                                     system claimed this call
  284.         memFullErr            -108    iconHandle could not be allocated
  285.         desktopDamagedErr    -1305    The desktop database has become corrupted - 
  286.                                     the Finder will fix this, but if your
  287.                                     application is not running with the
  288.                                     Finder, use PBDTReset or PBDTDelete
  289.         afpItemNotFound        -5012    Information not found
  290. */
  291.  
  292. /*****************************************************************************/
  293.  
  294. pascal    OSErr    DTSetComment(short vRefNum,
  295.                              long dirID,
  296.                              ConstStr255Param name,
  297.                              ConstStr255Param comment);
  298. /*    ¶ Set a file or directory's Finder comment field.
  299.     The DTSetComment function sets a file or directory's Finder comment
  300.     field. The volume must support the Desktop Manager because you only
  301.     have read access to the Desktop file.
  302.  
  303.     vRefNum    input:    Volume specification.
  304.     dirID    input:    Directory ID.
  305.     name    input:    Pointer to object name, or nil when dirID
  306.                     specifies a directory that's the object.
  307.     comment    input:    The comment to add. Comments are limited to 200 characters;
  308.                     longer comments are truncated.
  309.     
  310.     Result Codes
  311.         noErr                0        No error
  312.         nsvErr                -35        Volume not found
  313.         ioErr                -36        I/O error
  314.         fnfErr                –43        File or directory doesn’t exist
  315.         paramErr            -50        Volume doesn't support this function
  316.         wPrErr                –44        Volume is locked through hardware
  317.         vLckdErr            –46        Volume is locked through software
  318.         rfNumErr            –51        Reference number invalid
  319.         extFSErr            -58        External file system error - no file
  320.                                     system claimed this call.
  321.         desktopDamagedErr    -1305    The desktop database has become corrupted - 
  322.                                     the Finder will fix this, but if your
  323.                                     application is not running with the
  324.                                     Finder, use PBDTReset or PBDTDelete
  325.     
  326.     __________
  327.     
  328.     Also see:    DTCopyComment, FSpDTCopyComment, FSpDTSetComment, DTGetComment,
  329.                 FSpDTGetComment
  330. */
  331.  
  332. /*****************************************************************************/
  333.  
  334. pascal    OSErr    FSpDTSetComment(const FSSpec *spec,
  335.                                 ConstStr255Param comment);
  336. /*    ¶ Set a file or directory's Finder comment field.
  337.     The FSpDTSetComment function sets a file or directory's Finder comment
  338.     field. The volume must support the Desktop Manager because you only
  339.     have read access to the Desktop file.
  340.  
  341.     spec    input:    An FSSpec record specifying the file or directory.
  342.     comment    input:    The comment to add. Comments are limited to 200 characters;
  343.                     longer comments are truncated.
  344.     
  345.     Result Codes
  346.         noErr                0        No error
  347.         nsvErr                -35        Volume not found
  348.         ioErr                -36        I/O error
  349.         fnfErr                –43        File or directory doesn’t exist
  350.         wPrErr                –44        Volume is locked through hardware
  351.         vLckdErr            –46        Volume is locked through software
  352.         rfNumErr            –51        Reference number invalid
  353.         paramErr            -50        Volume doesn't support this function
  354.         extFSErr            -58        External file system error - no file
  355.                                     system claimed this call.
  356.         desktopDamagedErr    -1305    The desktop database has become corrupted - 
  357.                                     the Finder will fix this, but if your
  358.                                     application is not running with the
  359.                                     Finder, use PBDTReset or PBDTDelete
  360.     
  361.     __________
  362.     
  363.     Also see:    DTCopyComment, FSpDTCopyComment, DTSetComment, DTGetComment,
  364.                 FSpDTGetComment
  365. */
  366.  
  367. /*****************************************************************************/
  368.  
  369. pascal    OSErr    DTGetComment(short vRefNum,
  370.                              long dirID,
  371.                              ConstStr255Param name,
  372.                              Str255 comment);
  373. /*    ¶ Get a file or directory's Finder comment field (if any).
  374.     The DTGetComment function gets a file or directory's Finder comment
  375.     field (if any) from the Desktop Manager or if the Desktop Manager is
  376.     not available, from the Finder's Desktop file.
  377.  
  378.     IMPORTANT NOTE: Inside Macintosh says that comments are up to
  379.     200 characters. While that may be correct for the HFS file system's
  380.     Desktop Manager, other file systems (such as Apple Photo Access) return
  381.     up to 255 characters. Make sure the comment buffer is a Str255 or you'll
  382.     regret it.
  383.     
  384.     vRefNum    input:    Volume specification.
  385.     dirID    input:    Directory ID.
  386.     name    input:    Pointer to object name, or nil when dirID
  387.                     specifies a directory that's the object.
  388.     comment    output:    A Str255 where the comment is to be returned.
  389.     
  390.     Result Codes
  391.         noErr                0        No error
  392.         nsvErr                -35        Volume not found
  393.         ioErr                -36        I/O error
  394.         fnfErr                -43        File not found
  395.         paramErr            -50        Volume doesn't support this function
  396.         rfNumErr            –51        Reference number invalid
  397.         extFSErr            -58        External file system error - no file
  398.                                     system claimed this call.
  399.         desktopDamagedErr    -1305    The desktop database has become corrupted - 
  400.                                     the Finder will fix this, but if your
  401.                                     application is not running with the
  402.                                     Finder, use PBDTReset or PBDTDelete
  403.         afpItemNotFound        -5012    Information not found
  404.         
  405.     __________
  406.     
  407.     Also see:    DTCopyComment, FSpDTCopyComment, DTSetComment, FSpDTSetComment,
  408.                 FSpDTGetComment
  409. */
  410.  
  411. /*****************************************************************************/
  412.  
  413. pascal    OSErr    FSpDTGetComment(const FSSpec *spec,
  414.                                 Str255 comment);
  415. /*    ¶ Get a file or directory's Finder comment field (if any).
  416.     The FSpDTGetComment function gets a file or directory's Finder comment
  417.     field (if any) from the Desktop Manager or if the Desktop Manager is
  418.     not available, from the Finder's Desktop file.
  419.  
  420.     IMPORTANT NOTE: Inside Macintosh says that comments are up to
  421.     200 characters. While that may be correct for the HFS file system's
  422.     Desktop Manager, other file systems (such as Apple Photo Access) return
  423.     up to 255 characters. Make sure the comment buffer is a Str255 or you'll
  424.     regret it.
  425.     
  426.     spec    input:    An FSSpec record specifying the file or directory.
  427.     comment    output:    A Str255 where the comment is to be returned.
  428.  
  429.     Result Codes
  430.         noErr                0        No error
  431.         nsvErr                -35        Volume not found
  432.         ioErr                -36        I/O error
  433.         fnfErr                -43        File not found
  434.         paramErr            -50        Volume doesn't support this function
  435.         rfNumErr            –51        Reference number invalid
  436.         extFSErr            -58        External file system error - no file
  437.                                     system claimed this call.
  438.         desktopDamagedErr    -1305    The desktop database has become corrupted - 
  439.                                     the Finder will fix this, but if your
  440.                                     application is not running with the
  441.                                     Finder, use PBDTReset or PBDTDelete
  442.         afpItemNotFound        -5012    Information not found
  443.         
  444.     __________
  445.     
  446.     Also see:    DTCopyComment, FSpDTCopyComment, DTSetComment, FSpDTSetComment,
  447.                 DTGetComment
  448. */
  449.  
  450. /*****************************************************************************/
  451.  
  452. pascal    OSErr    DTCopyComment(short srcVRefNum,
  453.                               long srcDirID,
  454.                               ConstStr255Param srcName,
  455.                               short dstVRefNum,
  456.                               long dstDirID,
  457.                               ConstStr255Param dstName);
  458. /*    ¶ Copy the file or folder comment from the source to the destination object.
  459.     The DTCopyComment function copies the file or folder comment from the
  460.     source to the destination object.  The destination volume must support
  461.     the Desktop Manager because you only have read access to the Desktop file.
  462.     
  463.     srcVRefNum    input:    Source volume specification.
  464.     srcDirID    input:    Source directory ID.
  465.     srcName        input:    Pointer to source object name, or nil when srcDirID
  466.                         specifies a directory that's the object.
  467.     dstVRefNum    input:    Destination volume specification.
  468.     dstDirID    input:    Destination directory ID.
  469.     dstName        input:    Pointer to destination object name, or nil when
  470.                         dstDirID specifies a directory that's the object.
  471.     
  472.     Result Codes
  473.         noErr                0        No error
  474.         nsvErr                -35        Volume not found
  475.         ioErr                -36        I/O error
  476.         fnfErr                –43        File or directory doesn’t exist
  477.         wPrErr                –44        Volume is locked through hardware
  478.         vLckdErr            –46        Volume is locked through software
  479.         paramErr            -50        Volume doesn't support this function
  480.         rfNumErr            –51        Reference number invalid
  481.         paramErr            -50        Volume doesn't support this function
  482.         extFSErr            -58        External file system error - no file
  483.                                     system claimed this call.
  484.         desktopDamagedErr    -1305    The desktop database has become corrupted - 
  485.                                     the Finder will fix this, but if your
  486.                                     application is not running with the
  487.                                     Finder, use PBDTReset or PBDTDelete
  488.         afpItemNotFound        -5012    Information not found
  489.         
  490.     __________
  491.     
  492.     Also see:    FSpDTCopyComment, DTSetComment, FSpDTSetComment, DTGetComment,
  493.                 FSpDTGetComment
  494. */
  495.  
  496. /*****************************************************************************/
  497.  
  498. pascal    OSErr    FSpDTCopyComment(const FSSpec *srcSpec,
  499.                                  const FSSpec *dstSpec);
  500. /*    ¶ Copy the desktop database comment from the source to the destination object.
  501.     The FSpDTCopyComment function copies the desktop database comment from
  502.     the source to the destination object.  Both the source and the
  503.     destination volumes must support the Desktop Manager.
  504.     
  505.     srcSpec        input:    An FSSpec record specifying the source object.
  506.     dstSpec        input:    An FSSpec record specifying the destination object.
  507.     
  508.     Result Codes
  509.         noErr                0        No error
  510.         nsvErr                -35        Volume not found
  511.         ioErr                -36        I/O error
  512.         fnfErr                –43        File or directory doesn’t exist
  513.         wPrErr                –44        Volume is locked through hardware
  514.         vLckdErr            –46        Volume is locked through software
  515.         paramErr            -50        Volume doesn't support this function
  516.         rfNumErr            –51        Reference number invalid
  517.         paramErr            -50        Volume doesn't support this function
  518.         extFSErr            -58        External file system error - no file
  519.                                     system claimed this call.
  520.         desktopDamagedErr    -1305    The desktop database has become corrupted - 
  521.                                     the Finder will fix this, but if your
  522.                                     application is not running with the
  523.                                     Finder, use PBDTReset or PBDTDelete
  524.         afpItemNotFound        -5012    Information not found
  525.         
  526.     __________
  527.     
  528.     Also see:    DTCopyComment, DTSetComment, FSpDTSetComment, DTGetComment,
  529.                 FSpDTGetComment
  530. */
  531.  
  532. /*****************************************************************************/
  533.  
  534. #ifdef __cplusplus
  535. }
  536. #endif
  537.  
  538. #include "OptimizationEnd.h"
  539.  
  540. #endif    /* __MOREDESKTOPMGR__ */
  541.  
  542.  
  543.